Popular Request/By Popular Request (Arsenal Computer)(SysOptics Distribution System).ISO/amiga1/avm1_19.lha/AGMSPlaySound.doc

Text File | 1994-04-06 | 12KB | 271 lines

                          AGMSPlaySound

AGMSPlaySound is a Modula-2 program by Alexander G. M. Smith which
plays arbitrarily large IFF and raw sound samples from disk.

Sound Samples

Since AGMSPlaySound doesn't load the whole sample into memory, you can
play samples longer than your memory size (up to 2 gigabytes).  It also
leaves lots of memory free for other uses (such as running several other
AGMSPlaySounds simultaneously, for quadraphonic sound :-).  Unlike some
other sound playing programs, AGMSPlaySound can play from floppy disk
without annoying pauses.  It achieves this performance by processing the
IFF file headers and locating the sound data before starting to play.
It also opens all the files before playing so that no time is wasted
during playback.


Files

In addition to playing huge sound files, you can specify several samples
to be played one after the other by listing the file names in the order
you want to hear them (useful for combining phoneme samples to make
spoken words).  You can even have the parts on different disk devices.
Yes, this program supports floppies too! Note that floppies can only
play back data at a rate of at most 10000 Hz (disable any disk caching
programs, they waste CPU time when reading files larger than the cache).

The files to be played can be specified with wildcard patterns since
this program uses the ARP library.  You can even specify the ALL keyword
to recursively play all the files in all directories (note that since
all files stay open until the program has finished, you may run out of
fast memory if you have lots of files, not to mention the memory used
for storing the full path name of the files!).  I've found and fixed the
bug that caused memory trashing with ALL, apparently ARP expects an
undocumented parameter to the FindFirst function when it is used
recursively.  It was documented in 1987 and was then taken out from the
documentation.  Unfortunately, they kept on using it in arp.library
version 39.1.  Hence the trashing problem.

How do you get those big sound files? Either use a sound digitizer and
an Amiga with lots of memory or use AGMSRecordSound.  AGMSRecordSound
multitasks while it records arbitrarily long sounds directly to hard
disk.


Help

Most of the arguments to the program are obvious.  Just type a ? as the
argument to get the standard ARP / AmigaDOS command template.  A second
? typed at the template prompt will print the program credits (now in
AmigaDOS 2.0 compatible ANSI text).  The Verbose option also explains in
more detail what the current settings are.  Ok, maybe they aren't
obvious.  I'll describe the parameters in detail near the end of this
message.


Stolen Channels

The program supports audio priorities and recovers gracefully from
stolen audio channels (waits until a channel is free or the user types
control-C).  In fact, if you are playing more than one sample, it will
backtrack over multiple files to the one which was being played when the
sound channel was stolen (one of the advantages to keeping all the files
open until the program ends).  By the way, I've set it up to give
preference for using the right hand sound channels before the left hand
ones (sorry, I haven't had time to do Stereo, have a look at several
other newer player programs (OmniPlay, DSound, etc) which do).


Bug Fixes and New Features

I've found a bug in the M2Sprint IFFR.mod module for reading IFF files
containing CAT objects.  Fortunately, M2Sprint includes the source code
for the libraries so I was able to fix it in the December 27 1990
version.  I like that.  The problem comes from not using the listContext
that was carefully set up to read the CAT.  Instead, they use the
clientContext parameter to get the address of the procedure to call.
For CAT objects, clientContext is nil so some random memory address gets
called.  Where did I find it? AmigaVision uses CAT objects for
containing the elements of your program.  Now if someone out there has
IFF files with LIST or PROP objects, I'd appreciate a copy for
testing...  Never mind, AGMSMakeFilm generates that kind of file.  By
the way, if you want to do video off a hard disk with a stereo sound
track, try out the AGMS*Film series.

Also fixed (a feature really :-) is the file closing algorithm.  Files
that were examined but have no sounds are now closed after examination
rather than at the end of the program.  The memory used for their path
names is also freed at this time.  This should make it easier to play
all the sounds on your hard disk without running out of memory.

The NoWait option was added in the September 6, 1992 version.

Faster disk access (got rid of some unnecessary seeks - really huge
sound files will be examined much more quickly), 2.0 compatible ANSI
text and swapping of control-E and control-F were added in the
June 13, 1993 version.

While working on AGMSTranscribeSound (a player that lets you go
backwards and forwards and set bookmarks), I found the AmigaDOS 2.0
lockup bug, AbortIO sometimes hangs!  You tell it to abort an audio
write request and it just sits there.  Fortunately, stealing the channel
will wake it up (run another program that steals channels, like most mod
players).  I've worked around it in the July 17 1993 version by doing a
CMD_FLUSH before doing any AbortIOs.

Added an ARexx port December 19 1993, after pestering by Al Villarica.


Feedback

If you have any feature requests or find any bugs, please send me a
message.  I'm on several of the Ottawa BBX's (a BBS written by SteveX)
and my commercial info service names are listed in the program's second
help message ([e-mail], [e-mail]).


Distribution

AGMSPlaySound is FreeWare.  Copyright (c) 1993 by Alexander G. M. Smith.
That means that you can use it freely, can't blame me for anything that
goes wrong (there are probably a few bugs left), can't claim that you
wrote it, and you shouldn't expect more from it than you paid me for it.


Files/...

This argument to the program is a list of file names.  The files will be
played in the order listed.  Each name can include wildcards (standard
Amiga plus ARP style), if it selects more than one file, that group of
files will be played in alphabetical order.  If you want to repeat a
sound sample, just specify its name several times.


Buffers/K

This parameter specifies the number of chip ram buffers to use for the
sound.  You need at least 2.  While the system is playing one buffer,
the others can be filled from disk.  The default is 5.  Try the verbose
command switch to watch the buffers being filled and to see how changing
the number of buffers affects performance.


Size/K

This parameter sets the size of each chip ram sound buffer.  The default
is 10000 bytes, the maximum is 131072 bytes.  So, if you have 5 buffers
and each is 10000 bytes then you will use a total of 50000 bytes of chip
ram.  There is also a small amount of fast ram used for each buffer
(message records and other small things).  For best performance, use
large buffers.  That is because DOS can read a large chunk of data
faster than several small chunks (less overhead).


Hz/K

This parameter controls the playback rate for raw sound samples (in
other words, when AGMSPlaySound can't figure out the speed which the
sample was recorded with).  It is in units of samples per second, or
bytes per second since each sample is one byte long (compact disks have
2 byte samples and thus sound better).  The default is about 10000hz.

It is internally translated into a code value for the hardware.  Since
the hardware doesn't have all that many code values, only a few
frequencies are actually available.  A frequency near the one you
specified will be picked.


IFFLikeRaw/S

If this switch is specified, IFF sound samples will be treated a bit
like raw samples.  The IFF header information about the playback
frequency and volume level will be ignored; the default Hz and Volume
parameters will be used instead.  This is useful if you want to hear an
IFF file at lower or higher pitch than it was recorded with.  Also, the
full chunk size will be used instead of the size specified in the IFF
sound parameters for one shot sounds.


Volume/K

This specifies the volume level of the playback.  0 means quiet, 64 is
loud.  IFF files contain their own volume settings which override this
parameter.


Verbose/S

When this command switch is used, lots of interesting messages will be
displayed.  When examining IFF files, the structure and contents will be
shown (even for non-sound files like pictures - try it on a picture to
see what I mean).  All the parameter settings will be shown.  The
parsing of your wildcards will be shown.  And during playback, the
program will describe what it is doing (useful for seeing if your buffer
settings are good).


Priority/K

No, this is not the task priority.  This is the priority that
AGMSPlaySound uses when it is fighting with another program for control
of an audio channel.  Larger positive values give more priority.  Some
programs (like the Sonix player) grab the channels with priority 127
(the maximum).  With that high a priority, no other program can take
over the channel (other users with priority 127 have to wait).  The
default value is -90, good for background music.

When a higher priority request comes in, the lower priority sound
channel user looses the channel (the channel is "stolen").
AGMSPlaySound will detect the theft and put in a fresh request for the
sound channel.  That request will stay pending until the high priority
hog has finished making noise (oink, oink!), then AGMSPlaySound will be
woken up by the Amiga OS and will resume playing from where it was cut
off.


All/S

This switch will turn on recursive directory searching.  Normally, when
you specify a directory or one is encountered during wildcard checking,
the directory will be skipped.  When ALL is used, the directory contents
will be examined for sound files.


NoRaw/S

This one will disable the playing of raw (non-IFF) files.  Useful when
you use wildcards to play a bunch of files and you only want to hear the
ones with IFF sounds in them.


NoWait/S

The last switch! Normally AGMSPlaySound will wait for an audio channel
to become free before playing.  If NoWait is specified, AGMSPlaySound
will terminate if there are no audio channels free.  This means that you
won't hear (or see, unless Verbose is on) anything if a higher priority
sound is playing in all channels.  Similarly, if the channel being used
gets stolen, AGMSPlaySound will try to find another one, and if it can't
it will exit rather than waiting for another one.  Added on September 6,
1992 to satisfy James Atwill's wish for a Cron cuckoo clock that didn't
collect up cuckoos while Experiment-IV was playing SoundTracker modules.


ARexx: StopPlaying

If you have ARexx installed, AGMSPlaySound will open an ARexx port
called "AGMSPlaySound" (note the case of the letters) and respond to
commands.  Currently, the only command is "StopPlaying" which will stop
the playback, much like a Control-C does.  Have a look at the Test.rexx
script included with the archive to see how to use AGMSPlaySound from
ARexx.  You can thank Al Villarica for requesting this feature.


Control-C Etc.

Control-C will abort the program as soon as it has finished whatever it
is doing.

Control-E can be used during the file examining stage to start playing
sound samples (stops the file examining activity).  During sound
playback, it will move backwards and play the previous sound sample.
The data that has been already read for the current sample will finish
playing before the previous sample is heard.

Control-F used during sample playing makes AGMSPlaySound move forwards
to the next sound sample.

- Alex